/**
 * 角色工具模块
 * 
 * 本模块提供了一系列用于处理角色和权限关系的工具函数，是系统权限控制的基础。
 * 它实现了基于角色的访问控制(RBAC)模型的核心逻辑，用于决定用户可以执行的操作。
 * 
 * 系统角色体系：
 * - 超级管理员(roleType=1)：系统最高权限，可执行所有操作
 * - 管理员(roleType=2)：区域级管理权限，可管理其所在区域的内容和用户
 * - 编辑(roleType=3)：内容创建者，只能管理自己创建的内容
 * 
 * 主要功能：
 * - 角色类型判断（是否为特定角色）
 * - 角色名称转换（数字类型转为可读名称）
 * - 操作权限判断（特定角色是否可执行特定操作）
 * 
 * @module utils/roleUtils
 */

/**
 * 判断是否为超级管理员
 * 超级管理员(roleType=1)拥有系统中的所有权限，包括用户管理、权限分配等特权操作
 * 
 * @param roleType 角色类型，1=超级管理员，2=管理员，3=编辑
 * @returns 是否是超级管理员
 */
export const isSuperAdmin = (roleType: number): boolean => {
  return roleType === 1; // 只有roleType为1时才是超级管理员
};

/**
 * 判断是否为管理员
 * 管理员(roleType=2)拥有区域内的管理权限，可以管理其所在区域的内容和普通用户
 * 
 * @param roleType 角色类型，1=超级管理员，2=管理员，3=编辑
 * @returns 是否是管理员
 */
export const isAdmin = (roleType: number): boolean => {
  return roleType === 2; // 只有roleType为2时才是管理员
};

/**
 * 判断是否为编辑
 * 编辑(roleType=3)拥有内容创建和修改权限，是系统中的内容生产者
 * 
 * @param roleType 角色类型，1=超级管理员，2=管理员，3=编辑
 * @returns 是否是编辑
 */
export const isEditor = (roleType: number): boolean => {
  return roleType === 3; // 只有roleType为3时才是编辑
};

/**
 * 根据角色类型获取角色名称
 * 将数字角色类型转换为可读的中文角色名称，用于界面显示
 * 
 * @param roleType 角色类型，1=超级管理员，2=管理员，3=编辑
 * @returns 角色的中文名称
 */
export const getRoleName = (roleType: number): string => {
  // 使用switch语句根据角色类型返回对应的中文名称
  switch (roleType) {
    case 1:
      return '超级管理员'; // 最高权限角色
    case 2:
      return '管理员'; // 区域管理角色
    case 3:
      return '编辑'; // 内容创建角色
    default:
      return '未知角色'; // 处理未定义的角色类型
  }
};

/**
 * 检查用户是否有权限执行特定操作
 * 基于角色类型(roleType)判断用户对不同操作的权限
 * 
 * 权限规则：
 * - 超级管理员(roleType=1)：拥有所有操作权限
 * - 管理员(roleType=2)：可以查看、创建、更新、删除和审核
 * - 编辑(roleType=3)：只能查看、创建和更新自己的内容
 * 
 * 操作类型定义：
 * - view: 查看内容的权限
 * - create: 创建新内容的权限
 * - update: 修改内容的权限
 * - delete: 删除内容的权限
 * - audit: 审核内容的权限
 * 
 * @param roleType 角色类型，1=超级管理员，2=管理员，3=编辑
 * @param operation 操作类型：'view'=查看，'create'=创建，'update'=更新，'delete'=删除，'audit'=审核
 * @returns 是否有权限执行指定操作
 */
export const hasOperationPermission = (
  roleType: number,
  operation: 'view' | 'create' | 'update' | 'delete' | 'audit'
): boolean => {
  // 超级管理员拥有所有权限
  if (roleType === 1) return true; // 最高权限角色可以执行任何操作
  
  // 管理员权限
  if (roleType === 2) {
    switch (operation) {
      case 'view':    // 查看权限
      case 'update':  // 更新权限
        return true; // 管理员可以查看和更新内容
      case 'create':  // 创建权限
      case 'delete':  // 删除权限
      case 'audit':   // 审核权限
        return true;  // 管理员可以创建、删除和审核内容
      default:
        return false; // 未定义的操作默认无权限
    }
  }
  
  // 编辑权限
  if (roleType === 3) {
    switch (operation) {
      case 'view':    // 查看权限
        return true; // 编辑可以查看内容
      case 'create':  // 创建权限
        return true;  // 编辑可以创建自己的内容
      case 'update':  // 更新权限
        return true;  // 编辑可以更新自己的内容（注：通常需要配合所有权检查）
      case 'delete':  // 删除权限
      case 'audit':   // 审核权限
        return false; // 编辑不能删除内容和进行审核
      default:
        return false; // 未定义的操作默认无权限
    }
  }
  
  // 未知角色类型，默认无权限
  return false; // 安全起见，未知角色不授予任何权限
};

/**
 * 导出所有角色工具函数
 * 便于统一引入使用
 */
export default {
  isSuperAdmin,            // 判断是否为超级管理员
  isAdmin,                 // 判断是否为管理员
  isEditor,                // 判断是否为编辑
  getRoleName,             // 获取角色名称
  hasOperationPermission   // 检查操作权限
}; 